/*
 * Strategy.java
 *
 * Created on 31 de Janeiro de 2010, 21:29
 *
 * To change this template, choose Tools | Template Manager
 * and open the template in the editor.
 */

package intopo.game;

import java.io.PrintStream;

/**
 * This interface is used to mark a class as a strategy for some game.
 *
 * <p> Implementations of this interface should take into consideration the
 * contract of method {@code getMutated(RandomEngine)}. This method should
 * return a mutated copy of the calling instance.  The calling instance
 * <b>MUST NOT</b> be changed.  The method that calculates the next
 * generation of an evolutionary algorithm relies on this specification.
 *
 * <p> Each strategy has a <i>bin</i> which is a positive integer. They are
 * usefull when a strategy has floating point parameters and one has to
 * divide the domain of parameters in small subsets.
 *
 * @author Pedro Mariano
 */
public interface Strategy<S extends Strategy>
{
	/**
	 * Return a mutant of this strategy with all genes mutated. The caller parameters MUST
	 * NOT be changed.
	 *
	 * <p> Implementors can use the pseudo-random number generator in class {@code Cache}.
	 *
	 * @return a mutated copy of this strategy.
	 *
	 * @see intopo.evogame.partnerselection.Cache#supply
	 */
	public S getMutantAllGenes ();
	/**
	 * Return a mutant of this strategy with a single gene mutated. The caller parameters MUST
	 * NOT be changed.
	 *
	 * <p> Implementors can use the pseudo-random number generator in class {@code Cache}.
	 *
	 * @return a mutated copy of this strategy.
	 *
	 * @see intopo.evogame.partnerselection.Cache#supply
	 */
	public S getMutantSingleGene ();
	/**
	 * Return the bin of this strategy.  Strategies with the same bin are
	 * considered similar, i.e. their parameters have similar values. This
	 * allows classification of strategies with parameters that have
	 * floating point values or that have a large domain.
	 *
	 * <p>A bin is different from a integer that represents a strategy.
	 *
	 * @return The bin of this strategy.
	 */
	public int getBin ();
	/**
	 * Return {@code true} if this strategy can be considered a
	 * cooperator. This largely depends on other partners.
	 *
	 * @return {@code true} if this is cooperative strategy.
	 */
	public boolean isCooperator ();
	/**
	 * Prints this strategy in the given text stream.  The written data must be read from a constructor that accepts a text stream encapsulated in a {@code Scanner} instance.
	 *
	 * @param ps The stream where the strategy is printed.
	 */
	public void print (PrintStream ps);
	/**
	 * Writes this strategy in the given binary stream.
	 * @param dos The stream where the strategy is written.
	 * @throws java.io.IOException if an I/O error occurs.
	 */
	public void write (java.io.DataOutputStream dos)
	  throws java.io.IOException;

}
